Client-side Data Cache

IN THIS PAGE

Defining a Client-side Data Cache
Client-side Data Cache Editor
Persisting Data
Other Settings

Description

Using the Client-side Data Cache.

Discussion

The client-side data cache allows you to define one or more 'data items' that are cached on the client-side so that you can reference this data in a UX component. The data in the data cache is in the form of Javascript arrays.

Watch Video - Client-side Data Cache

For example, you might define a client-side data cache with these items:

customers
orders
products

For each item in the data cache you specify the server side query that generates the JSON data for the data item. For example, you might specify that the data for the 'customer' data item is obtained by executing a SQL SELECT command against a SQL Server database.

The data for the 'orders' data item might be obtained by executing some custom Xbasic code that returns a string of JSON data.

The data source for a data item can be:

SQL: a SQL query
nested SQL queries: multiple nested SQL queries that return complex JSON data (with nested arrays of data). For example you might have a query for all customers in Boston, with all orders and payments for each customer as a nested array and then all order details for each order as a nested array
Xbasic: any Xbasic code that returns data in JSON format
static: a static string of data in JSON format

The data in a data-item can, optionally, be saved on the client-side so that it is available when you are running the application in disconnected mode. When you choose to save the data on the client, you have the option of storing the data in:

local storage
a file on the device (option only applies when you are running in a Cordova shell)

The amount of data that can be stored in local storage is limited. If you store data in a file on the device you will be able to store significantly more data than would be possible in local storage.

The UX has methods that allow you to refresh the data in a data item and to read the data from a data item into a Javascript array. When you read data from a data item into an array you can, optionally, specify filter and order conditions so that only 'records' that meet your filter criteria are in the array returned by the read method.

You can specify that the data in a data-item should be 'delayed'. This means that when the UX is initially rendered, the query for the data item is not performed and no data is initially sent to the client. Only when the user executes an explicit command to 'refresh' the data item will an Ajax callback to the server be made and then the data item query is performed and the data are sent to the client.

If you have specified that the data in a data item should be persisted to Local Storage, there is no way of knowing, at the time the query to get the data for the data item is performed, if the data that is returned to the client will actually be able to be stored in Local Storage - because there is not enough available space in Local Storage. Therefore, when you specify that a data item should be stored on the client side you can also specify an event handler that will get fired if the data could not be successfully persisted to Local Storage. This will allow you to display some UI to inform the user to enter more selective search criteria for the query that returns the data for the data item.

If you want to use the FileSystem option in a Cordova application you must include the Device, File and File Transfer plugins when you build your Cordova application.

Defining a Client-side Data Cache

To define a client-side data cache, you open the Client-side Data Cache Editor. There are two ways to open the editor. You can use the dropdown menu by clicking the Menu button, as shown below:

images/menu_client_side_data_cache_editor.jpg

Or, you can click the smart-field for the 'Client-side data cache' property on the Properties pane in the UX builder

images/client-side-data-cache-property.gif

Client-side Data Cache Editor

The Client-side Data Cache editor, shown in the image below, shows the names of data items in the Data Cache. The dialog show summary information about each data item.

To edit an item in the Data Cache, click the 'Edit item' button, or double click on the item in the list. This will open the Data Item editor.

For each item you can specify:

Item type: specify how the data for the data item are obtained. The choices are SQL Query, Nested SQL Query, Static Data and Xbasic
Delay query until explicit refresh: specify if the data in the data item should only be computed after the user has issued an explicit 'refresh' command. IMPORTANT: If you want to persist the data in a data item to a file or to Local Storage, then this option must be checked.
Security groups: specify the security groups for this data item. If the user is not logged in an a member of one of the specified security groups, the data in the data item will be empty.
Server-side enable expression: specify a server-side expression (typically involving session variables). If this expression evaluates to false, the data in the data item will be empty.

Persisting Data

If the Delay query until explicit refresh property has been checked, the dialog shows additional properties that allow you to specify that the data item should be stored on the device.

The options for Store where are:

Local Storage: stored in Local Storage on the device. If there is not sufficient space in Local Storage the Javascript defined in the persistToLocalStorageFailed property will execute.
FileSystem: stored in a file on the device. This will only work if the UX is running in a Cordova shell. (Files are downloaded to a folder called '__AADataCache' on the device)
FileSystemPreferred: If the UX is running in a Cordova shell, the data are stored in a file on the device, otherwise, data are stored in Local Storage.

IMPORTANT: If you are persisting to the file system and you are using Xbasic to generate the data for the data items, be sure to generate properly formed JSON. For example: [ {"name" : "fred"} ] and not [ {name: 'fred'} ]

When Store data on device option is checked you can specify a Maximum payload size property. This is the maximum size (in bytes) that a query is allowed to return. If you specify the default value of -1 there is no maximum. This property is designed to allow you to protect against the user trying to download too much data to the device. When the

If the Maximum payload size property is set to some value greater than -1, the payloadSizeExceeded Javascript Event property is shown. You can put code in this property to alert the user that their query for the data item returned too much data and they they must enter a more restrictive query.

Other Settings

If any of the data items in your Client-side Data Cache are configured to store data in the file system on the device then you can set additional settings in the Other Settings tab of the Client-side Data Cache editor.

These settings control whether a progress bar is shown while the device is downloading the data from the server to be stored in files on the device.

If you are storing large amounts of data on the device you will generally want to show the user a progress bar so that they know that something is happening.

You can specify the color and width of the progress bar and you can also specify a placeholder or an explicit element id for the position of the progress indicator. Say for example, and element with an ID of 'progress1' and you want to display the progress indicator in this element, you specify the Placheholder for progress indicator as element:progress1

Before file download begins: This event fires after the Ajax callback to get the data for the data items that are being refreshed has completed, but before the device actually starts downloading data.

The use case for the Before file download begins event is as follows:

Say you have defined a Client-side data cache with a large number of data items, (or a few data items, some of which return a large amount of data.) The Ajax callback to refresh all data items will take some time on the server to complete. While the server is busy performing the queries to get the data in the data items, the user has no indication that anything is happening. So, it is likely that you will want to display a wait.. dialog when the user clicks a button to refresh the data in the data items (which triggers the Ajax callback to the server). Once the server has obtained all of the data it sends a response back to the client telling the client to start downloading the data. At this point the progress indicator will start moving, giving feedback to the user. The Before file download begins event will allow you to dismiss the wait... dialog (since it is no longer needed -- the user can now watch the progress indicator).